To access the TRIDENT's services, one of the available authorization mechanisms must be used. In particular:

Client applications must use OAuth 2.0 access tokens.
Delegated process servers must use JSON Web tokens (JWT).

OAuth 2.0 Access Tokens

[RSE_AUTH_INTEG] describes the OAuth 2.0 authorization code grant and client credentials grant flows that the client applications can use for obtaining access tokens from the TRIDENT. When obtaining the token requires consent from the user who owns the resource, the authorization server redirects the user's browser to an identity provider in the domain for authenticating the user (or identifies them via single sign-on).

TRIDENT issues Bearer type OAuth tokens; the permissions these tokens grant are determined by the associated scopes. To invoke a service with this type of authorization, the client application sends the request using TLS and includes the access token in an HTTP authorization header as follows:

Authorization: Bearer {token}

Where {token} is the access token received in the response from the Obtain a Token operation (the access_token property). TRIDENT does not allow indicating the token in a parameter of the URL.

TRIDENT's REST services, acting as the OAuth resource servers, validate these access tokens and uses them to control the access of the client application to the service. They mainly check that the token is still valid, the associated identity domain, if the token was issued with the consent of a user in particular and the scopes granted.

JSON Web Tokens (JWT)

The JSON Web token standard defines a compact and secure format for representing claims that must be exchanged between two parties. A signed JWT token has three parts: a header (header), which identifies the algorithm used to generate the signature; the data payload, i.e., the claims to be exchanged; and a signature (signature), which provides the authenticity and integrity to the token.

To invoke a service with this type of authorization, the application sends the request to TRIDENT using TLS and includes the token in an HTTP authorization header as follows:

Authorization: JWS {token}

Where {token} is the signed and serialized JSON Web token as per the compact format defined in JSON Web Signature.

Authorization for Delegated Process Servers

sfly-delegated-auth-token JWT tokens grant administrative access to TRIDENT's services with the following permissions:

urn:safelayer:eidas:account:user:list
urn:safelayer:eidas:account:user:attributes:manage
urn:safelayer:eidas:account:user:passwords:validate
urn:safelayer:eidas:account:user:passwords:delete

Therefore, using this type of authorization, the delegated process servers can perform operations such as identify users via unique attributes, manage identity attributes stored in the user accounts and validate passwords stored in the user accounts.

Token construction

The header is a JSON object with the following parameters:

{ 
    "alg" : "HS256",
    "typ" : "sfly-delegated-auth-token"
}

Parameter	Usage	Description
`alg`	Required	Signature algorithm. Must take `HS256` as its value, corresponding to the HMAC SHA-256 algorithm.
`typ`	Required	Token type. Must have the proprietor value `sfly-delegated-auth-token`.

The token data (payload) is structured in a JSON object as follows:

{ 
    "iss" : {string},
    "sub" : {string},
    "nonce" : {string},
    "iat" : {number}
}

Parameter	Usage	Description
`iss`	Required	Distinguished name (DN) of the delegated process server that uses the token for invoking the TRIDENT's services.
`sub`	Required	Identity domain of the user whose account is to be managed. This is the identity domain under which user authentication takes place when the delegated process server is invoked. It should normally match the `issuer` field value of the delegation request (see [RSE_AUTH_INTEG] for more details on the delegation protocol).
`nonce`	Required	Random value that helps safeguard against replay attacks. We recommend using a random value of at least 10 bytes in base64 format.
`iat`	Required	Time the token was issued, represented as the number of seconds from 1970-01-01 00:00:00 UTC until the current UTC time.

To construct the JWT token:

Encode the header, first in UTF-8 and then in base64url (see [RFC 4648]).
Encode the data (payload), first in UTF-8 and then in base64url.
Concatenate both with a “.” character (a full stop).
Calculate the HMAC-SHA256 signature (see [RFC 2104]) of the previous string and encode the signature in base64url. As the signature key, the SHA-256 hash of the secret shared between TRIDENT and the delegated process server (secret) must be used. The secret must be encoded in UTF-8 before calculating its hash.

signature := base64url(hmac_sha256(base64url(utf8(header)) + '.' + base64url(utf8(payload)), hash_sha256(utf8(secret))))
Concatenate the encoding of the header, the data and the signature with a “.” (full stop) character.

token := base64url(utf8(header)) + '.' + base64url(utf8(payload)) + '.' + signature

The result obtained is the signed JWT token serialized in compact form, as it is to be included in the Authorization header of the HTTP request.